---
title: 图片
description: 学习如何在 Astro 项目中包含图片。
i18nReady: true
---
import Since from '~/components/Since.astro';


在 Astro 项目中，有很多种在网站中使用图片的方式。无论是用存储在项目中的图片，还是链接外部图片，亦或从像 CMS（内容管理系统）或 CDN（内容分发网络）这样的地方加载图片，都没问题！

:::note[`astro:assets` (Experimental - coming in v3.0)]
实验性 `astro:assets` 模块将在 `astro@3.0` 中默认启用.

请按照 [资源（实验性）使用指南](/zh-cn/guides/images/) 开始使用新的图片解决方案！

**下面的一些建议可能与实验性标志不兼容。如果你正在使用 `astro:assets` 请参考资源页面。**
:::

### 在 `.astro` 文件中

你可以在 `.astro` 文件中使用标准的 HTML `<img>` 或 `<img />` 元素来展示图片，同时也支持所有 HTML 图片属性。

src 属性是必需的，其格式取决于图像的存储位置以及你是否启用了对资源的实验性支持：

```astro
---
// src/pages/index.astro
import rocket from '../images/rocket.svg';
---
<!-- 位于其它服务器上的图片 -->
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro">

<!-- 存储在 public/assets/stars.png 的本地图片 -->
<img src="/assets/stars.png" alt="一片繁星闪烁的夜空。">

<!-- 存储在 src/images/rocket.svg 的本地图片 -->
<img src={rocket} alt="外空中的一架火箭。"/>
```

### 在 Markdown 文件中

可以在 `.md` 文件中使用 Markdown 标准语法 `![]()`，或 HTML 标准语法 `<img>` 标签，来调用位于 `public/` 文件夹下或其它服务器上的图片。

如果你无法将图片保留在 `public/` 中，我们建议启用 [资源的实验性支持](/zh-cn/guides/images/), 或使用 `.mdx` 文件格式，该格式允许你将导入的组件与类似 Markdown 的语法结合起来。使用 [MDX 集成](/zh-cn/guides/integrations-guide/mdx/) 向 Astro 添加对 MDX 的支持。
```md
<!-- src/pages/post-1.md -->

# 我的 Markdown 页面

<!-- 存储在 public/assets/stars.png 的本地图片 -->
![一片繁星闪烁的夜空。](/assets/stars.png)
<img src="/assets/stars.png" alt="一片繁星闪烁的夜空。">

<!-- 位于其它服务器上的图片 -->
![Astro](https://docs.astro.build/assets/logomark-light.png)
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro">
```

### 在 MDX 文件中

你可以在 .mdx 文件中使用标准 Markdown `![]()` 语法或 JSX  的 `<img />` 标签来显示 `public/ ` 文件夹或远程服务器中的图片。

此外，你也可以导入和使用位于项目 `src/` 目录中的图像，就像在 Astro 组件中一样。


```mdx title="src/pages/post-1.mdx"

import rocket from '../images/rocket.svg';

# My MDX Page

// 存放在项目中 src/images/rocket.svg 路径的图片
<img src={rocket} alt="外空中的一架火箭。"/>

// 存放在项目中 public/assets/stars.png 路径的图片
![一片繁星闪烁的夜空。](/assets/stars.png)
<img src="/assets/stars.png" alt="一片繁星闪烁的夜空。" />

// 位于其它服务器上的图片
![Astro](https://docs.astro.build/assets/logomark-light.png)
<img src="https://docs.astro.build/assets/logomark-light.png" width="25" alt="Astro" />
```

### UI 框架中的组件

当在 [UI 框架组件](/zh-cn/core-concepts/framework-components/)（例如 React、Svelte）中添加图像时，请使用适合该框架的图像语法。



## 存放图片的位置

### `src/`

存储在 `src/`中的图像可以由组件（`.astro`，`.mdx`和其他 UI 框架）使用，但不能在 Markdown 文档中使用。

如果你必须使用 Markdown 文档，我们建议你将图像保存在 ['public/']（#public） 中或 [远程](#使用-cms-或-cdn-上的图片) 存储他们。

从任何组件文档中的 **相对文档路径** 或 [导入别名](/zh-cn/guides/aliases/) 导入它们，然后像使用 `src`属性一样使用。

```astro
---
// src/pages/index.astro

// Access images in `src/images/`
import logo from '../images/logo.png';
---
<img src={logo} width="40" alt="Astro 的图标" />
```

### `public/`

存储在 `public/` 中的图像可以被组件（`.astro`，`.mdx`和其他UI框架）和Markdown文档使用。

然而，位于 `/public` 目录中的文件始终按原样提供或复制，不进行任何处理。如果你在 Markdown 文件之外使用图像，我们建议尽可能将本地图像保存在 `src/` 中，以便 Astro 对其进行转换、优化和打包。

`src` 属性是 **相对于 public 文件夹的**。在 Markdown 中，你可以使用 `![]()` 表示。

```astro
---
// src/pages/index.astro

// 存取放在 `public/images/` 里的图片
---
<img src="/images/logo.png" />
```

### `src/assets/` （实验性）

请参阅 [资源（实验性）](/zh-cn/guides/images/) 指南，了解如何启用 `/assets/` 文件夹的实验性用法。

这将需要你更新现有图片，删除当前的 Astro 图片集成，并且还需要额外的手动更改以利用其某些新功能。

## Astro 的图片集成

:::note[将在 v3.0 中弃用]
Astro v3 将不再主动支持 [`@astrojs/image`](https://github.com/withastro/astro/tree/main/packages/integrations/image) 集成

我们建议你尽早删除它，并使用将内置在 `astro@3.0` 中的实验性 `astro:assets` 模块。

请按照 [资源（实验性）使用指南](/zh-cn/guides/images/) 开始使用新的图片解决方案！

**`astro:assets` 目前还不能完全替代 `@astrojs/image` ，但它正在被积极开发中。**
:::

有关在 Astro v2 中使用 `@astrojs/image` 的文档，请参阅 [`@astrojs/image` 文档](https://github.com/withastro/astro/blob/main/packages/integrations/image/README.md)

## 使用 CMS 或 CDN 上的图片

Image CDN 可与 Astro 配合使用，可将图片的完整网址作为 `<img>` 标签中的 `src` 属性或 Markdown 标记

如果 CDN 提供了 Node.js SDK ，则可以在项目中使用它。例如，[Cloudinary 的 SDK](https://cloudinary.com/documentation/node_integration) 可以生成带有相应 `src` 属性 的 ` <img>` 标签。

## Alt Text

并非所有用户都能以相同的方式查看图片，因此在使用图片时可访问性是一个特别重要的问题。使用 `alt` 属性为图片提供 [描述性替代文本](https://www.w3.org/WAI/tutorials/images/)。

此属性对于映像集成的 `<Image />` 和 `<Picture/>` 组件是必需的，如果未提供替代文本，这些组件将引发错误。

如果图像只是装饰性的（即无助于理解页面）请设置 `alt=""`，以便屏幕阅读器知道忽略该图像。

## 社区开发的集成

除了官方的 [`@astrojs/image`](/zh-cn/guides/integrations-guid/image/) 集成外，社区还开发了[社区图片集成](https://astro.build/integrations?search=images)，用于处理和优化 Astro 项目中的图片。
